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1. GENERAL 



1.1. Scope 

This document describes the software requirements of the Gatherer. The Gatherer is a 
major component in the XaCCT 3.0 system. 

1.2. Applicable Documents 

[1] System Specification Document for the XaCCT 3.0 System, XACCT-SSD, 
Revision 1.0. 

[2] Gatherer-CEM Interface Description Document, Gatherer-CEM-IDD, Revision 
1.0. 

[3] Software Requirements Specification for the Central Event Manager, 
CEM-SRS, Revision 1.0. 

[4] Gatherer-Gatherer Interface Description Document, Gatherer-IDD, Revision 
1.0. 

In any case of discrepancy between any of the above documents and this document, 
this document will take precedence. 

1.3. System Overview 

The Gatherer is responsible for gathering information from one or more Information 
Sources (IS). The gatherer configures the different ISs according to information sent 
from the CEM. At specific times, the Gatherer sends network information in UNIRs to 
the CEM to be stored (and, possibly, merged with other UNIRs) in the CDB. 

The Gatherer relies on Information Source Modules (ISMs) to access the IS, and is, 
thus, designed to be completely independent of the particular ISs it interfaces. The 
Gatherer is responsible to upgrade load and run ISMs without interference to the rest of 
the Gatherers capabilities or other ISs. 

The Gatherer is designed to be a lightweight process that may be run on non-dedicated 
computers as a background task (not consuming considerable CPU, memory, disk 
space or network resources). Under other circumstances, the Gatherer may be run on a 
dedicated computer, or be allowed to utilize more computer and network resources. 
The parameters that determine the amount of resources consumed are determined via 
control of the CEM. 

There are two distinct behaviors an ISM may have. An ISM may behave as an 
Synchronous ISM (SISM) or Asynchronous ISM (AISM). An ISM may concurrently 
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exhibit both behaviors and be considered both an SISM and an AISM. An AISM is a 
source of information that may asynchronously (randomly, without synchronization with 
any other event) produce UNIRs that represent some sort of network event including 
some auxiliary information regarding this event. An SISM does not generate events, but 
is rather requested to handle some request for some information, it handles the request 
synchronously (the caller waits for the reply) and returns a reply. 

To summarize, the Gatherer's functionality includes: 

1 . To access ISs in order to collect network information (either synchronously or 
asynchronously). 

2. Performing enhancement of UNIRs. 

3. Monitoring state of ISs connected to the Gatherer. 

4. Routing UNIRs from one Gatherer to another. 

5. Being controllable by the CEM completely (start/stop/configuration etc.). 

6. Buffering outgoing traffic. 

7. Maintaining a cache of information obtained from ISs or other Gatherers. 

8. Maintaining an LMS (Local Module Storage) of ISMs (Information Source 
Modules). 

9. Downloading ISMs from CEM on demand. 

10. Automatically upgrading Gatherer SW from CEM when a newer version is 
available at CEM. 

11. Allowing for encryption of all communication links within the system 
(communication between Gatherer and CEM and between Gatherers). 

1 .4. System Use Cases 

Listed below is a list of CEM use-cases. The details of each use-case are discussed in 
"4. Use Cases". 

1 . Startup. 

2. Shutdown. 

3. Error occurs. 

4. Install/Remove/Configure an IS. 

5. Handle CEM request to set/get properties of Gatherer/IS. 

6. Receive network event from AISM. 

7. Receive request for information from SISM. 

8. Route a message to another Gatherer. 

9. Enhance a UNIR received from another Gatherer. 

10. Synchronize Clocks. 

1 .5. System Major Objects 

This section lists the major analysis-objects identified by the use cases discussed in "4. 
Use Cases". 

1 . Gatherer- The core of the Gatherer that loads and runs ISMs and enhances and 
routes UNIRs. A Gatherer communicates with other Gatherers to perform to 
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route UNIRs for further processing, or to request information from SISMs 
connected to the other Gatherers. 

2. CEM - The Central Event Manager that controls the Gatherer's operation and 
eventually collects all data collected by the Gatherer. 

3. Cache - The cache is used to store recent network information collected from 
SISMs to be checked before accessing a local (connected to the same Gatherer) 
or remote (connected to another Gatherer) SISM. The cache is of a limited and 
remotely configurable size. 

4. ISM - The ISM communicates with the Information Source that it manages and 
with its container Gatherer. The IS Module is not part of the Gatherer installation 
but is transferred dynamically from the CEM. The reason for that is that the 
upgrade of the IS should be simple and in a single, central place. The IS Module 
communicates with its managed IS in the following forms: 



a) 


Ethernet. 


b) 


UDP/IP. 


c) 


TCP/IP. 


d) 


SNMP. 


e) 


Telnet. 


f) 


File access. 


g) 


ODBC. 


h) 


Native API. 



The ISM may behave either as an AISM, an SISM or both. 

5. LMS - The Gatherer stores ISMs in a Local Module Storage of a configurable 
size. 

6. Output Buffer - All network information to be sent to other entities in the system 
(CEM or Gatherers), is stored in this buffer. The buffer is maintained in memory 
and its size is configurable from CEM. 

7. Log File - All errors are recorded into this log file. The log file is cyclic and may 
be accessed remotely by the CEM.. 

8. UNIR - Unified Network Information Record are produced and processed in 
many ways by the Gatherer. 

9. Route - Computational flows of information indicating what to do with each 
incoming request, whether to enhance it, and how, and to whom to send it 
(another Gatherer or CEM).. 

10. ISCM - The Gatherer relays information transparently between an ISM and its 
configuration module, the ISCM. 

11. Configuration - The Gatherer configuration includes the following types of 
configuration parameters: 

a) Gatherer parameters (Output Buffer size, Cache size, LMS size, 
maximum CPU/network usage, time synchronization intervals). 

b) ISM parameters (AISM and/or SISM behavior, ID of ISM, IS-specific 
parameters specifying how to access IS). 
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c) Enhancement/Routing parameters (detailed instructions on how to handle 
incoming traffic from Gatherers and AISMs connected to the Gatherer, 
what to do with them and to whom to forward them). 

1 .6. System Non-Functional Requirements 

1.6.1. Hardware & Software Requirements 

The Gatherer shall be able to run (in different binary versions) on the following 
hardware platforms: 

• Sun Sparc running Solaris 2.5. 

• Intel-based PC with a Pentium or Pentium Pro processor running either 
Windows NT 4.0 or Windows 95. 

In any case, a TCP/IP stack must be properly installed. 

1.6.2. Performance Requirements 

The critical issue with regards to performance is keeping up the pace imposed by 
handling the incoming data and requests in time to receive new ones without 
spilling the output buffer. The performance depends, therefore on the influx and 
the computer's speed. 

Nonetheless, the computer resources shall be carefully monitored and shall not 
exceed a configurable parameter. 

1.6.3. Security Requirements 

The Gatherer may be exposed to security risks in its communication and 
configuration. All communications between Gatherers and between the Gatherer 
and the CEM shall be designed to be encrypted and digitally signed in the future. 
The local storage of the Gatherer shall not contain any confidential information. 
Administration of the Gatherer is performed remotely by the CEM and imposes 
security requirements of the CEM. 
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2. EXTERNAL INTERFACES 

2.1. Gatherer-CEM Interface 

This interface is described completely in [2]. 
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3. USER INTERFACE 



The Gatherer has a very limited user interface. All its configuration is set through the 
CUI, besides initial parameters set during installation. 

The Gatherer initially runs as a minimized fixed-size window. This window allows 
viewing of the product name, version, logo (possibly animated), and status, and 
contains two buttons. One button minimizes the window, and the other is used to 
terminate the application. Below is a schematic of this window: 





r > 

Logo/ 
Animation 

I J 


App Title 

Version ... 
Copyright ... 


Close 
Exit 




Status: ... 









Clicking "Close" minimizes the window. Clicking "Exit" displays a confirmation dialog, 
confirming shuts down the application, otherwise, the dialog is removed. The dialog is 
modal, but both the window and the dialog are non-blocking (all application activity 
continues). 

During installation, the following parameters are set by the user: 

1. The Port of the Gatherer. 

2. The IP and Port of the CEM to which this Gatherer connects to. 

3. The directory in which to install the Gatherer (all Gatherer components will be placed 
within this directory or its sub-directories). 

These parameters can be changed only by reinstalling the software. 

The software can be removed (shared components - used by other applications, will be 
removed only if not referenced). 

Below are the Gatherer items that are remotely configurable (the defaults themselves 
are not maintained at the Gatherer, but rather defaults used by CEM/CUI as default 
values for the configuration purposes): 

1 . Output buffer size (default 1 00 KB). 

2. Cache Size (default 1 MB). 
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3. LMS size (default 1 MB). 

4. Maximum CPU percentage, network usage percentage or BW (set individually 
default 10% for all). 

5. Time synchronization interval & moving average length (default 30 minutes and 
90 minutes respectively). 

6. Log size (default 256 KB). 

7. Route/Enhancement parameters - details are at design level. 

8. IS parameters (for each ISM) - details are at design level. 
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4. USE CASES 



4.1. Startup 

Qverview/Pu rpose 

To start the Gatherer's operation after proper or improper shutdown (failure). 

The Gatherer initially "knows" only the IP (implicitly) and the Port on which it is 
running and the IP and Port of the CEM. Upon startup, It sends and message to 
initialize communication with the CEM including the version of the Gatherer SW 
itself. If this SW is old, the CEM will instruct the Gatherer to upgrade its SW 
version. The CEM will then set the Gatherer's configuration, including which ISs 
are accessed by the Gatherer, using which ISMs (type and version), and using 
which parameters. If the Gatherer does not have the ISM of the correct version in 
its LMS, it will request that ISM from the CEM. The Gatherer also receives from 
the CEM the configuration of the enhancement/route handled by the Gatherer. 
The last point at which collection took place is also negotiated (possibly with 
CEM assistant) - TBD. After all Gatherer-related settings are configured, all 
operations are started. 

Actor/Stimulus 

OS loader or user manually (after shutdown). 

Frequency 

Medium - once every system startup/shutdown or failure. 

Alternative Courses 
None. 

Interaction Diagram 
See in [1]. 

4.2. Shutdown 



Overview/Purpose 

To stop running on the computer and to allow proper termination of connections. 

Actor/Stimulus 

The user, the OS or an exception handler. 

Frequency 

Low - once every system startup/shutdown or failure. 
Alternative Courses 

The stimulus may change and this may distinguish between a full shutdown and 
an expedited procedure. In case of failure, a short procedure will shutdown 
ASAP recording the circumstances to the log. 
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Interaction Diagram 



User 
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Gatherer 




ISM 




IS 




CEM 
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4.3. Error Occurs 

Overview/Purpose 

To handle error conditions in an orderly fashion, and to, possibly, convey this 
information to the CEM. 

Actor/Stimulus 

Any problem condition within Gatherer or with respect to Gatherer's external 
interfaces. 

Frequency 

Low - hopefully, errors do not occur often. 

Alternative Courses 
None. 

Interaction Diagram 
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4.4. Install/Remove/Configure an IS 

Overview/Purpose 

The user may choose to install, remove or reconfigure ISs. 

Actor/Stimulus 

User via CUI and CEM or CEM under special circumstances. 

Frequency 

Low - IS configuration is relatively static. 

Alternative Courses 

Installing, removing and configuring are similar, but distinct courses. 

Interaction Diagram 
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4.5. Handle CEM Request to set/get properties of Gatherer/IS 



Overview/Purpose 

The CEM may request to set or get various Gatherer/IS parameters. 

Actor/Stimulus 

Request from CEM. 

Frequency 

Low - this is likely to occur during reconfiguration, startup/shutdown, errors, etc. 

Alternative Courses 
None. 

Interaction Diagram 

A slight modification on "4.4. Install/Remove/Configure an IS". 

4.6. Receive network event from an AISM 

Overview/Purpose 

AISMs may originate a network event. The Gatherer is configured (by the CEM) 
to expect this and take specific actions in response. These involve enhancing the 
information using SISMs or routing the whole enhanced network event to another 
Gatherer or to the CEM after all enhancements are complete. In all cases an 
SISM is accessed, the Cache is first checked to contain the information. 

Every access to an SISM has a time-out and if it exceeded, both the Gatherer 
awaiting the response and the SISM discontinue attempt to resolve the request. 

Actor/Stimulus 

Any network event that is detected at an ISM configured to act as an AISM. 
Frequency 

Very High - up to every packet traversing a link will cause this use-case. 
Alternative Courses 

A remote SISM may be accessed for enhancing the information. In this case, the 
local Cache is first checked, if the requested enhancement is not found, a remote 
Gatherer is requested to supply the information (the remote Gatherer is 
connected locally to the SISM that can supply the response). 

Interaction Diagram 

The following pseudo-code describes the actions taken by the Gatherer upon 
receipt of UNIR from an AISM. 

Receive UNIR from AISM 

while should be enhanced 

if enhancement cached 
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retrieve from cache 
enhance 

else if enhancement local 

call local SISM for enhancement 
if not timed out 
enhance 

else 

do not enhance 

else // enhancement from SISM at remote Gatherer 
call remote SISM for enhancement 
if not timed out 
enhance 

else 

do not enhance 

if should be routed 

send UNIR (partially enhanced) to target Gatherer 

else - 

send UNIR (fully enhanced) to CEM 
This is also described schematically in the following interaction diagram: 
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4.7. Receive request for information from SISM 

Overview/Purpose 

A remote Gatherer needs to get information from a Gatherer, and it makes sense 
to: a) Cache this information at the requesting end; b) Not pass the whole UNIR 
containing large amounts of data through this Gatherer. 

Actor/Stimulus 

Remote Gatherer request. 

Frequency 

High - This happens in every enhancement, but the caching mechanisms should 
reduce this load. 

Alternative Courses 
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Interaction Diagram 
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4.8. Route a message to another Gatherer 

Overview/Purpose 

To relay any message to the Gatherer that is the destination of the message. 

The Gatherer maintains a fixed route-table controlled by the CEM and 
downloaded to the Gatherer as part of its configuration. The route table is simply 
a table identifying to which Gatherer to send a message in order to deliver it to 
another Gatherer. 

Actor/Stimulus 

Receipt of message destined to another Gatherer. 
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Frequency 

High - some traffic may permanently be routed via a Gatherer. 

Alternative Courses 
None. 



Interaction Diagram 
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4.9. Enhance a UNIR received from another Gatherer 

Overview/Purpose 

To add information to the collected information. The rationale of distributing the 
enhancement among several Gatherers is: 

a. The 1 st Gatherer can not efficiently access the enhanced information locally. 

b. The 1 st Gatherer is not powerful, or is under some other resource constraints 
that make it inappropriate to process the UNIR further at that site. 

c. The UNIR requires several enhancements at the 2 nd Gatherer and instead of 
utilizing the Cache mechanism, it would be better to do all processing at the 
2 nd Gatherer. 

d. The enhancement is of considerable size and the bandwidth of the 
connection between the 2 nd Gatherer and the CEM is larger than that of the 
bandwidth between the 1 st Gatherer and the CEM. 

e. This may be computed to conserving total network utilization. 

f. Hit ratio of Cache at 1 st Gatherer is low, either because the size of the Cache 
is small or the data is diverse, and therefore the Cache is ineffective. 

Actor/Stimulus 

UNIR received for enhancement from another Gatherer. 
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Frequency 

Very High - if such enhancements are necessary during the enhancement route 
of a UNIR, ail UNIRs will traverse this link. 

Alternative Courses 
None. 

Interaction Diagram 

See "4.6. Receive network event from an AISM", the diagram contains this 
use-case. 

4.10. Synchronize Clocks 



See in [3]. 
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